package com.kexio.pay.service;

import java.util.Map;

import com.kexio.common.dto.Result;
import com.kexio.pay.dto.PaymentRequest;
import com.kexio.pay.dto.PaymentResponse;
import com.kexio.pay.entity.PaymentCallback;
import com.kexio.pay.entity.PaymentOrder;
import com.kexio.pay.enums.PaymentStatus;

/**
 * 支付服务接口
 * 
 * @author Kexio Team
 * @since 1.0.0
 */
public interface PaymentService {
    
    /**
     * 创建支付订单
     * 
     * @param request 支付请求
     * @return 支付响应
     */
    Result<PaymentResponse> createPayment(PaymentRequest request);
    
    /**
     * 查询支付状态
     * 
     * @param orderNo 订单号
     * @return 支付状态
     */
    PaymentStatus queryPaymentStatus(String orderNo);
    
    /**
     * 查询支付订单
     * 
     * @param orderNo 订单号
     * @return 支付订单
     */
    PaymentOrder queryPaymentOrder(String orderNo);
    
    /**
     * 关闭支付订单
     * 
     * @param orderNo 订单号
     * @return 关闭结果
     */
    Result<Boolean> closePayment(String orderNo);
    
    /**
     * 取消支付订单
     * 
     * @param orderNo 订单号
     * @param reason 取消原因
     * @return 取消结果
     */
    Result<Boolean> cancelPayment(String orderNo, String reason);
    
    /**
     * 处理支付回调
     * 
     * @param provider 支付提供商
     * @param callback 回调数据
     * @return 处理结果
     */
    Result<Boolean> handleCallback(String provider, PaymentCallback callback);
    
    /**
     * 同步支付状态 (主动查询第三方)
     * 
     * @param orderNo 订单号
     * @return 同步结果
     */
    Result<PaymentStatus> syncPaymentStatus(String orderNo);
    
    /**
     * 获取支付统计信息
     * 
     * @param timeRange 时间范围 (today, week, month)
     * @return 统计信息
     */
    Map<String, Object> getPaymentStatistics(String timeRange);
    
    /**
     * 检查订单是否可以支付
     * 
     * @param orderNo 订单号
     * @return 检查结果
     */
    Result<Boolean> checkPaymentAvailable(String orderNo);
    
    /**
     * 重新发起支付 (原订单失败后)
     * 
     * @param orderNo 原订单号
     * @param newPaymentMethod 新支付方式
     * @return 支付响应
     */
    Result<PaymentResponse> retryPayment(String orderNo, String newPaymentMethod);
    
    /**
     * 获取支付方式列表
     * 
     * @param scene 支付场景
     * @return 支付方式列表
     */
    Map<String, Object> getAvailablePaymentMethods(String scene);
    
    /**
     * 预创建订单 (不调用第三方，仅创建本地订单)
     * 
     * @param request 支付请求
     * @return 订单信息
     */
    Result<PaymentOrder> preCreateOrder(PaymentRequest request);
    
    /**
     * 处理订单超时
     * 
     * @return 处理的订单数量
     */
    int processExpiredOrders();
    
    /**
     * 验证回调签名
     * 
     * @param provider 支付提供商
     * @param callback 回调数据
     * @return 验证结果
     */
    boolean verifyCallbackSignature(String provider, PaymentCallback callback);
}
